Reverse Literate Programming

Knuth’s Literate Programming system allows an author to design and describe a program hierarchically according to the method of stepwise refinement. The result is source code, which can be read sequentially like a book, section after section. This helps when reading printed source code, but on screen source code is read rather selectively like an encyclopedia. There the programmer wants a system which allows, possibly even encourages, selective browsing; zoom in at interesting points; jump to other locations according to control flow or other semantic relationships. This is the approach chosen by hypertext systems. In this paper, we demonstrate a solution, called Reverse Literate Programming, which combines the advantages of Knuth’s method and of the hypertext approach. We implemented active text elements making it possible to have the source code as a hypertext screen document. A special command prints this document as a Literate Program, i.e. an essay, including documentation, pictures, and program code. The implementation was done in the Oberon system which offers powerful mechanisms for extending software in an object-oriented way. 1 . Introduction When developing or reusing software components, one is often forced to study source code. In many cases this code contains only little or even no design information, which makes it hard to read and understand it. This is the main reason, why software maintenance costs dominate over all other life-cycle costs. Standish (1984), for example, discovered, that the time needed to understand source code, causes 50 to 90 percent of the maintenance costs. Therefore high software quality, in form of readable source code, is the best way to save time and money for new developments. During the last years, different tools for constructing readable and maintainable code were suggested. One of these approaches, Literate Programming by Donald E. Knuth (1984), allows an author to design and describe a program hierarchically according to the method of stepwise refinement. The result is source code, which can be read sequentially like a book, section after section. This helps while reading the printed source code of a program. On the other hand, on screen programs are usually read rather selectively like an encyclopedia. The programmer does not want to have the source code in book form, but rather the opposite: a system which allows, possibly even encourages, selective browsing. Zoom in at interesting points or jump to other